Selection Parameters

// A Single View Specification
{
  ...,
  "params": [  // An array of named parameters.
    {
      "name": ...,
      "select": { // Selection
        "type": ...,
        ...
      }
    }
  ],
  "mark": ...,
  "encoding": ...,
  ...
}

Selection parameters define data queries that are driven by direct manipulation user input (e.g., mouse clicks or drags). A parameter becomes a selection when the select property is specified. This page discusses different properties of a selection.

Documentation Overview

• Common Selection Properties
  • type
  • Selection Projection with encodings and fields
    • Current Limitations
  • on
  • clear
  • resolve
• Point Selection Properties
  • toggle
  • Nearest
    • Current Limitations
• Interval Selection Properties
  • mark
  • translate
  • zoom

Common Selection Properties

For both selection types, the select object can take the following properties:

type

A selection’s type determines which data values fall within it by default:

• For point selections, only values that have been directly interacted with (e.g., those that have been clicked on) are considered to be “selected.”
• For interval selections, values that fall within both the horizontal (x) and vertical (y) extents are considered to be “selected.”

Selection Projection with encodings and fields

In the scatterplot example below, highlight multiplea single: Cylinder(s) Origin(s).

With interval selections, we can use the projection to restrict the region to just the horizontal (x) and/or vertical (y) dimensions.

Current Limitations

• Selections projected over aggregated fields/encodings can only be used within the same view they are defined in.
• Interval selections can only be projected using encodings.
• Interval selections projected over binned or timeUnit fields remain continuous selections. Thus, if the visual encoding discretizes them, conditional encodings will no longer work. Instead, use a layered view as shown in the example below. The bar mark discretizes the binned Acceleration field. As a result, to highlight selected bars, we use a second layered view rather than a conditional color encoding within the same view.

on

The on property modifies the event that triggers the selection.

For instance, a single rectangle in the heatmap below can now be selected on mouse hover instead.

clear

The clear property identifies which events must fire to empty a selection of all selected values (the empty property can be used to further determine the behavior of empty selections).

The following visualization demonstrates the default clearing behavior: select a square on click and clear out the selection on double click.

The following example clears the brush when the mouse button is released.

Note, in the above example, clearing out the selection does not reset it to its initial value. Instead, when the mouse button is released, the selection is emptied of all values. This behavior is subtly different to when the selection is bound to scales – clearing the selection out now resets the view to use the initial scale domains. Try it out below: pan and zoom the plot, and then double click.

resolve

When a selection is defined within a data-driven view (i.e., a view that is part of a facet or repeat), the desired behaviour can be ambiguous. Consider the scatterplot matrix (SPLOM) example below, which has an interval selection named brush. Should there be only one brush across all cells, or should each cell have its own brush? In the latter case, how should points be highlighted in all the other cells?

The aptly named resolve property addresses this ambiguity, and can be set to one of the following values (click to apply it to the SPLOM example, and drag out an interval in different cells):

• global (default) – only one brush exists for the entire SPLOM. When the user begins to drag, any previous brushes are cleared, and a new one is constructed.

• union – each cell contains its own brush, and points are highlighted if they lie within any of these individual brushes.

• intersect – each cell contains its own brush, and points are highlighted only if they fall within all of these individual brushes.

Point Selection Properties

In addition to all common selection properties, point selections support the following properties:

toggle

The toggle property customizes how user interaction can insert or remove data values from a point selection if they are or are not already members of the selection, respectively.

For example, you can highlight points in the scatterplot below by toggling them into the paintbrush selection when clicking with:
event.shiftKey event.altKey.

Nearest

The nearest propery accelerates user selection with an invisible voronoi diagram.

For example, in the scatterplot below, points nearestdirectly underneath the mouse cursor are highlighted as it moves.

The nearest transform also respects any position encoding projections applied to the selection. For instance, in the example below, moving the mouse cursor back-and-forth snaps the vertical rule and label to the nearest date value.

Current Limitations

• The nearest property is not supported for multi-element mark types (i.e., line and area). For these mark types, consider layering a discrete mark type (e.g., point) with a 0-value opacity as in the last example above.

Interval Selection Properties

In addition to all common selection properties, interval selections support the following properties:

mark

Every interval selection also adds a rectangle mark to the visualization, to depict the extents of the selected region.

The selection’s mark property can include the folloiwing properties to customize the appearance of this rectangle mark.

For example, the spec below imagines two users, Alex and Morgan, who can each drag out an interval selection. To prevent collision between the two selections, Morgan must press the shift key while dragging out their interval (while Alex must not). Morgan’s interval is depicted with the default grey rectangle, and Morgan’s with a customized red rectangle.

translate

The translate property allows a user to interactively move an interval selection back-and-forth.

For example, try to pan the brushscatterplot on dragshift-drag.

zoom

The zoom property allows a user to interactively resize an interval selection.

For example, you can zoom the brushscatterplot on wheelshift-wheel.